home *** CD-ROM | disk | FTP | other *** search
/ Stone Design / Stone Design.iso / Stone_Friends / Wave / WavesWorld / Source / Libraries / tcl7.4b3 / doc / TildeSubst.3 < prev    next >
Encoding:
Text File  |  1995-02-22  |  2.6 KB  |  73 lines
  1. '\"
  2. '\" Copyright (c) 1989-1993 The Regents of the University of California.
  3. '\" Copyright (c) 1994-1995 Sun Microsystems, Inc.
  4. '\"
  5. '\" See the file "license.terms" for information on usage and redistribution
  6. '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
  7. '\" 
  8. '\" @(#) TildeSubst.3 1.12 95/02/22 14:37:20
  9. '\" 
  10. .so man.macros
  11. .HS Tcl_TildeSubst tclc 7.0
  12. .BS
  13. .SH NAME
  14. Tcl_TildeSubst \- replace tilde with home directory in a file name
  15. .SH SYNOPSIS
  16. .nf
  17. \fB#include <tcl.h>\fR
  18. .sp
  19. char *
  20. .VS
  21. \fBTcl_TildeSubst\fR(\fIinterp\fR, \fIname\fR, \fIbufferPtr)
  22. .VE
  23. .SH ARGUMENTS
  24. .AS Tcl_DString *bufferPtr
  25. .AP Tcl_Interp *interp in
  26. Interpreter in which to report an error, if any.
  27. .AP char *name in
  28. File name, which may start with a ``~''.
  29. .AP Tcl_DString *bufferPtr
  30. .VS
  31. If needed, this dynamic string is used to store the new file name.
  32. At the time of the call it should be uninitialized or empty.  The
  33. caller must eventually call \fBTcl_DStringFree\fR to free up
  34. anything stored here.
  35. .VE
  36. .BE
  37.  
  38. .SH DESCRIPTION
  39. .PP
  40. This utility procedure does tilde substitution.  If \fIname\fR doesn't
  41. start with a ``~'' character, then the procedure returns \fIname\fR.
  42. If \fIname\fR does start with a tilde, then \fBTcl_TildeSubst\fR
  43. returns a new string identical to \fIname\fR except that the first
  44. element of \fIname\fR is replaced with the location of the home
  45. directory for the given user.  The substitution is carried out in
  46. the same way that it would be done by \fIcsh\fR.  If the tilde is
  47. followed immediately by a slash, then the \fB$HOME\fR environment
  48. variable is substituted.  Otherwise the characters between the
  49. tilde and the next slash are taken as a user name, which is
  50. looked up in the password file;  the user's home directory is
  51. retrieved from the password file and substituted.
  52. .PP
  53. If
  54. .VS
  55. \fBTcl_TildeSubst\fR has to do tilde substitution then it uses
  56. the dynamic string at \fI*bufferPtr\fR to hold the new string it
  57. generates.  After \fBTcl_TildeSubst\fR returns, the caller must
  58. eventually invoke \fBTcl_DStringFree\fR to free up any information
  59. placed in \fI*bufferPtr\fR.  The caller need not know whether or
  60. not \fBTcl_TildeSubst\fR actually used the string;  \fBTcl_TildeSubst\fR
  61. initializes \fI*bufferPtr\fR even if it doesn't use it, so the call to
  62. \fBTcl_DStringFree\fR will be safe in either case.
  63. .VE
  64. .PP
  65. If an error occurs (e.g. because there was no user by the given
  66. name) then NULL is returned and an error message will be left
  67. at \fIinterp->result\fR.  It is assumed that \fIinterp->result\fR
  68. has been initialized in the standard way when \fBTcl_TildeSubst\fR
  69. is invoked.
  70.  
  71. .SH KEYWORDS
  72. file name, home directory, tilde, user
  73.